27.14 Action Functions for display-buffer

The following basic action functions are defined in Emacs. Each of these functions takes two arguments: buffer, the buffer to display, and alist, an action alist. Each action function returns the window if it succeeds, and nil if it fails.

Function: display-buffer-same-window buffer alist

This function tries to display buffer in the selected window. It fails if the selected window is a minibuffer window or is dedicated to another buffer (see Dedicated Windows). It also fails if alist has a non-nil inhibit-same-window entry.

Function: display-buffer-reuse-window buffer alist

This function tries to display buffer by finding a window that is already displaying it.

If alist has a non-nil inhibit-same-window entry, the selected window is not eligible for reuse. If alist contains a reusable-frames entry, its value determines which frames to search for a reusable window:

• nil means consider windows on the selected frame. (Actually, the last non-minibuffer frame.)
• t means consider windows on all frames.
• visible means consider windows on all visible frames.
• 0 means consider windows on all visible or iconified frames.
• A frame means consider windows on that frame only.

Note that these meanings differ slightly from those of the all-frames argument to next-window (see Cyclic Window Ordering).

If alist contains no reusable-frames entry, this function normally searches just the selected frame; however, if the variable pop-up-frames is non-nil, it searches all frames on the current terminal. See Choosing Window Options.

If this function chooses a window on another frame, it makes that frame visible and, unless alist contains an inhibit-switch-frame entry (see Choosing Window Options), raises that frame if necessary.

Function: display-buffer-pop-up-frame buffer alist

This function creates a new frame, and displays the buffer in that frame’s window. It actually performs the frame creation by calling the function specified in pop-up-frame-function (see Choosing Window Options). If alist contains a pop-up-frame-parameters entry, the associated value is added to the newly created frame’s parameters.

Function: display-buffer-use-some-frame buffer alist

This function tries to display buffer by trying to find a frame that meets a predicate (by default any frame other than the current frame).

If this function chooses a window on another frame, it makes that frame visible and, unless alist contains an inhibit-switch-frame entry (see Choosing Window Options), raises that frame if necessary.

If alist has a non-nil frame-predicate entry, its value is a function taking one argument (a frame), returning non-nil if the frame is a candidate; this function replaces the default predicate.

If alist has a non-nil inhibit-same-window entry, the selected window is used; thus if the selected frame has a single window, it is not used.

Function: display-buffer-pop-up-window buffer alist

This function tries to display buffer by splitting the largest or least recently-used window (typically one on the selected frame). It actually performs the split by calling the function specified in split-window-preferred-function (see Choosing Window Options).

The size of the new window can be adjusted by supplying window-height and window-width entries in alist. To adjust the window’s height, use an entry whose CAR is window-height and whose CDR is one of:

• nil means to leave the height of the new window alone.
• A number specifies the desired height of the new window. An integer specifies the number of lines of the window. A floating-point number gives the fraction of the window’s height with respect to the height of the frame’s root window.
• If the CDR specifies a function, that function is called with one argument: the new window. The function is supposed to adjust the height of the window; its return value is ignored. Suitable functions are shrink-window-if-larger-than-buffer and fit-window-to-buffer, see Resizing Windows.

To adjust the window’s width, use an entry whose CAR is window-width and whose CDR is one of:

• nil means to leave the width of the new window alone.
• A number specifies the desired width of the new window. An integer specifies the number of columns of the window. A floating-point number gives the fraction of the window’s width with respect to the width of the frame’s root window.
• If the CDR specifies a function, that function is called with one argument: the new window. The function is supposed to adjust the width of the window; its return value is ignored.

If alist contains a preserve-size entry, Emacs will try to preserve the size of the new window during future resize operations (see Preserving Window Sizes). The CDR of that entry must be a cons cell whose CAR, if non-nil, means to preserve the width of the window and whose CDR, if non-nil, means to preserve the height of the window.

This function can fail if no window splitting can be performed for some reason (e.g., if the selected frame has an unsplittable frame parameter; see Buffer Parameters).

Function: display-buffer-below-selected buffer alist

This function tries to display buffer in a window below the selected window. This means to either split the selected window or use the window below the selected one. If it does create a new window, it will also adjust its size provided alist contains a suitable window-height or window-width entry, see above.

Function: display-buffer-in-previous-window buffer alist

This function tries to display buffer in a window previously showing it. If alist has a non-nil inhibit-same-window entry, the selected window is not eligible for reuse. If alist contains a reusable-frames entry, its value determines which frames to search for a suitable window as with display-buffer-reuse-window.

If alist has a previous-window entry, the window specified by that entry will override any other window found by the methods above, even if that window never showed buffer before.

Function: display-buffer-at-bottom buffer alist

This function tries to display buffer in a window at the bottom of the selected frame.

This either splits the window at the bottom of the frame or the frame’s root window, or reuses an existing window at the bottom of the selected frame.

Function: display-buffer-use-some-window buffer alist

This function tries to display buffer by choosing an existing window and displaying the buffer in that window. It can fail if all windows are dedicated to another buffer (see Dedicated Windows).

Function: display-buffer-no-window buffer alist

If alist has a non-nil allow-no-window entry, then this function does not display buffer. This allows you to override the default action and avoid displaying the buffer. It is assumed that when the caller specifies a non-nil allow-no-window value it can handle a nil value returned from display-buffer in this case.

To illustrate the use of action functions, consider the following example.

(display-buffer
 (get-buffer-create "*foo*")
 '((display-buffer-reuse-window
    display-buffer-pop-up-window
    display-buffer-pop-up-frame)
   (reusable-frames . 0)
   (window-height . 10) (window-width . 40)))

Evaluating the form above will cause display-buffer to proceed as follows: If a buffer called *foo* already appears on a visible or iconified frame, it will reuse its window. Otherwise, it will try to pop up a new window or, if that is impossible, a new frame and show the buffer there. If all these steps fail, it will proceed using whatever display-buffer-base-action and display-buffer-fallback-action prescribe.

Furthermore, display-buffer will try to adjust a reused window (provided *foo* was put by display-buffer there before) or a popped-up window as follows: If the window is part of a vertical combination, it will set its height to ten lines. Note that if, instead of the number 10, we specified the function fit-window-to-buffer, display-buffer would come up with a one-line window to fit the empty buffer. If the window is part of a horizontal combination, it sets its width to 40 columns. Whether a new window is vertically or horizontally combined depends on the shape of the window split and the values of split-window-preferred-function, split-height-threshold and split-width-threshold (see Choosing Window Options).

Now suppose we combine this call with a preexisting setup for display-buffer-alist as follows.

(let ((display-buffer-alist
       (cons
        '("\\*foo\\*"
          (display-buffer-reuse-window display-buffer-below-selected)
          (reusable-frames)
          (window-height . 5))
        display-buffer-alist)))
  (display-buffer
   (get-buffer-create "*foo*")
   '((display-buffer-reuse-window
      display-buffer-pop-up-window
      display-buffer-pop-up-frame)
     (reusable-frames . 0)
     (window-height . 10) (window-width . 40))))

This form will have display-buffer first try reusing a window that shows *foo* on the selected frame. If there’s no such window, it will try to split the selected window or, if that is impossible, use the window below the selected window.

If there’s no window below the selected one, or the window below the selected one is dedicated to its buffer, display-buffer will proceed as described in the previous example. Note, however, that when it tries to adjust the height of any reused or popped-up window, it will in any case try to set its number of lines to 5 since that value overrides the corresponding specification in the action argument of display-buffer.